docs(design): Notes UI audit + vault-selector design proposal - #114
Merged
Conversation
Captures the current state inventory (twenty routes, three nav primitives, where per-vault state is implicitly singular) and proposes a vault popover that fronts the hub's `/.well-known/parachute.json` vault list to fix the multi-vault-on-one-hub gap surfaced when Aaron dogfooded the new vault MCP install across four vaults. Surfaces ten broader UI improvement candidates with scope/leverage reads, engages with the surface-direction research note (parachute-patterns#54) on how Notes might evolve as a configured surface instance, and recommends a sequencing for the broader audit. No code changes. Doc-only PR — skips RC per patterns/governance.md rule 2. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Five citation/accuracy nits from #114 reviewer pass: - §2 well-known.ts line range corrected: WellKnownVaultEntry is at :11-22, not :35-54 (which was WellKnownServicesEntry). - §2 CORS framing: same-origin in standard installs (Notes at /notes/ on the hub origin); CORS-open header covers cross-origin deployments only. - §1 getActiveVault count anchored: 17 direct call sites + broader useVaultStore touched across dozens of components. The "113" figure was a rough estimate that would've gaslit a future implementer. - §2 beginOAuth reframe: authorize URL is built last after DCR + metadata discovery, so the vault-hint params bag is URL-decoration at the last step, not a structural change. Cheaper than the original framing implied. - §4 LensSettings rename residue: flagged the coordinated migration (hook → type → stored-key). The legacy lens storage path fallback is intentional and stays — only the hook surface renames. Plus open question added in §2: hub-origin discovery from VaultRecord. The popover needs to fetch /.well-known/parachute.json against a hub URL, but VaultRecord stores it as `issuer` (OAuth-time) without a clean "hub origin" surface. Design call deferred to Phase 2 PR. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… items After Aaron read the audit, he gave directional input that the doc should capture durably: - New "North star" subsection up top: Notes should serve as an Apple-Notes / Obsidian replacement. Three pillars — easy as Apple Notes, flexible as Obsidian-ish, Parachute-shaped via per-vault customization. Every improvement candidate now reads against this question: "does this make Notes a credible Apple-Notes replacement?" - §3 item #11: view-level text-size control. A device-local zoom knob (Default / Larger / Largest) affecting editor + read views. View preference, not content — markdown on disk stays untouched. Matches Apple Notes' affordance. - §3 item #12: unify capture surfaces. Collapse the /new + TextCapture + MemoCapture duality into one create-or-edit interface where the "quick" experience is the same surface with smart defaults (auto-title, role-driven tags, default path). Voice still uses its own input modality but hands off to the unified surface. - §5 sequence reordered: unified-capture + text-size now sit at positions 2 and 3, right after the vault popover. Authoring ease outranks chrome refinement because someone migrating from Apple Notes judges the app by day-one typing feel. No code, just the doc. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Design doc proposal — no code changes. Adds
design/2026-05-12-notes-ui-audit.md.boulder,default,gitcoin,techne) the Notes UI assumes one activevault at a time and offers no on-app way to discover the hub's
other vaults — every additional vault requires running OAuth from
/addagain with no prompt. Proposes a header popover that frontsthe hub's existing public
/.well-known/parachute.jsonvault list,with per-row "Connect" affordances. One component, one CORS-open
fetch, no new routes — solves the gap cheaply.
reads (search bar, header reshape, per-tab vault state, unified
create flow, network-error banner mirroring auth-error,
empty-state copy, vault badge, authoring polish, surface-aware
theming). Suggested sequencing in §5.
three-layer (vault/agent/surface) lens from
parachute-patterns/research/parachute-surface-direction.mdfuture "Notes is one configured surface" refactor. Argues
useVaultSettings+ Tag Roles is the prototype of whatsurface-config should look like.
Word count: ~3270.
Test plan
../../parachute-patterns/..., repo-localdesign doc) resolve.
parachute-patterns/patterns/governance.mdrule 2 — skips RC; no package.json bump.
Versioning
Doc-only — no version change. CHANGELOG entry added under
Unreleased.Process note
Phase 1 (this PR — design doc only).
Phase 2 — implementation PRs picking changes off the audit, in the
order proposed in §5.
🤖 Generated with Claude Code